Obtains a control’s optimal size and text placement.

OSErr GetBestControlRect (
    ControlRef inControl, 
    Rect *outRect, 
    SInt16 *outBaseLineOffset
);

inControl

A handle to the control to be examined.

outRect

On input, a pointer to an empty rectangle (0, 0, 0, 0). On return, the rectangle is set to the optimal size for the control. If the control doesn’t support getting an optimal size rectangle, the control’s bounding rectangle is passed back.

outBaseLineOffset

On input, a pointer to a signed 16-bit integer value. On return, the value is set to the offset from the bottom of control to the base of the text (usually a negative value). If the control doesn’t support optimal sizing or has no text, 0 is passed back.

function result

A result code.

DISCUSSION

You can call the GetBestControlRect function to automatically position and size controls in accordance with human interface guidelines. This function is particularly helpful in determining the correct placement of control text whose length is not known until run-time. For example, the StandardAlert function uses GetBestControlRect to automatically size and position buttons in a newly created alert box.

VERSION NOTES

This function is available with Appearance Manager 1.0 and later.

AVAILABILITY

Supported in Carbon. Available in Mac OS 8.1 and later when Carbon 1.0.2 or later is present.

© 2000 Apple Computer, Inc. — (Last Updated 5/8/2000)